<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  <link rel="stylesheet" href="docgen-resources/docgen.css" type="text/css">
  <meta name="generator" content="FreeMarker Docgen (DocBook 5)">
  <title>
    FreeMarker Manual - The types
  </title>
    <script type="text/javascript" src="docgen-resources/jquery.js"></script>
    <script type="text/javascript" src="docgen-resources/linktargetmarker.js"></script>
</head>
<body>

    <div class="navigation">
    <div class="breadcrumb">
<span class="breadcrumb">        You are here:
          <a href="index.html">Book</a>
            <b>></b>
          <a href="dgui.html">Template Author's Guide</a>
            <b>></b>
          <a href="dgui_datamodel.html">Values, Types</a>
            <b>></b>
          The types
</span>    </div>
    <div class="bookmarks">
<span class="bookmarks">Bookmarks:
<a href="alphaidx.html">Alphabetical Index</a>, <a href="gloss.html">Glossary</a>, <a href="ref.html">Reference</a>, <a href="app_faq.html">FAQ</a>, <a href="api/index.html">Java API</a>, <a href="../index.html">FreeMarker Home</a></span>    </div>
    <div class="pagers">
      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
<div class="pagerButton"><a href="dgui_template.html"><span class="hideA">Next page: </span>The Template</a></div><div class="pagerButton"><a href="dgui_datamodel_basics.html">Previous page</a></div><div class="pagerButton"><a href="dgui_datamodel.html">Parent page</a></div><div class="pagerButton"><a href="index.html">Contents</a></div>      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
    </div>
    </div>

<div id="mainContent">

  
  
  
  
  <h1 class="rank_section1"
        id="pageTopTitle">
<a name="dgui_datamodel_types"></a>The types  </h1>
    
    <div class="toc">
      <p>
        <b>
            Page Contents
        </b>
      </p>
      
  <ul class="noMargin">
      <li style="padding-bottom: 0.5em"><i><a href="#docgen_afterTheTOC">Intro.</a></i></li>
      <li>
        <a href="#dgui_datamodel_scalar">Scalars</a>
      </li>
      <li>
        <a href="#dgui_datamodel_container">Containers</a>
      </li>
      <li>
        <a href="#autoid_15">Subroutines</a>
  <ul >
      <li>
        <a href="#dgui_datamodel_method">Methods and functions</a>
      </li>
      <li>
        <a href="#dgui_datamodel_userdefdir">User-defined directives</a>
      </li>
      <li>
        <a href="#autoid_16">Function/method versus user-defined directive</a>
      </li>
  </ul>
      </li>
      <li>
        <a href="#autoid_17">Miscellaneous</a>
  <ul >
      <li>
        <a href="#dgui_datamodel_node">Nodes</a>
      </li>
  </ul>
      </li>
  </ul>
    </div>
    <a name="docgen_afterTheTOC"></a>
    
<p>The suppored types are:</p>    <div class="itemizedlist">
<ul>
          <li>
            <a href="#dgui_datamodel_scalar">Scalars:</a>

                <div class="itemizedlist">
<ul>
              <li>
                String
              </li>

              <li>
                Number
              </li>

              <li>
                Boolean
              </li>

              <li>
                Date
              </li>
            </ul>    </div>

          </li>

          <li>
            <a href="#dgui_datamodel_container">Containers:</a>

                <div class="itemizedlist">
<ul>
              <li>
                Hash
              </li>

              <li>
                Sequence
              </li>

              <li>
                Collection
              </li>
            </ul>    </div>

          </li>

          <li>
            Subroutines:

                <div class="itemizedlist">
<ul>
              <li>
                <a href="#dgui_datamodel_method">Methods and
                functions</a>
              </li>

              <li>
                <a href="#dgui_datamodel_userdefdir">User-defined
                directives</a>
              </li>
            </ul>    </div>

          </li>

          <li>
            Miscellaneous/seldom used:

                <div class="itemizedlist">
<ul>
              <li>
                <a href="#dgui_datamodel_node">Node</a>
              </li>
            </ul>    </div>

          </li>
        </ul>    </div>

            
  
  
  
  <h2 class="rank_section2"
        >
<a name="dgui_datamodel_scalar"></a>Scalars  </h2>


          <a name="topic.designer.scalarVariable"></a>

          <p>These are the basic, simple kind of values. They can
          be:</p>

              <div class="itemizedlist">
<ul>
            <li>
              <p>String: It is simple text, e.g., the name of a
              product.</p>

              <p>If you want to give a string value directly in the
              template, rather than use a variable that comes from the data
              model, you write the text between quotation marks, e.g.,
              <tt style="color: #A03D10">&quot;green mouse&quot;</tt> or <tt style="color: #A03D10">'green
              mouse'</tt>. (More details regarding the syntax can be
              found <a href="dgui_template_exp.html#dgui_template_exp_direct_string">later</a>.)</p>
            </li>

            <li>
              <p>Number: For example the price of a product.
              <span style="color:#333399; font-style:italic">Whole numbers and non-whole
              numbers are not distinguished; there is only a single number
              type. So for example 3/2 will be always 1.5, and never 1. Just
              like if you are using a calculator.</span></p>

              <p>If you want to give a numerical value directly in the
              template, then you write for example: <tt style="color: #A03D10">150</tt> or
              <tt style="color: #A03D10">-90.05</tt> or <tt style="color: #A03D10">0.001</tt>. (More
              details regarding the syntax can be found <a href="dgui_template_exp.html#dgui_template_exp_direct_number">later</a>.)</p>
            </li>

            <li>
              <p>Boolean: A boolean value represents a logical true
              or false (yes or no). For example, if a the visitor has been
              logged in or not. Typically you use booleans as the condition of
              the <tt style="color: #A03D10">if</tt> directive, like <tt style="color: #A03D10">&lt;#if
              loggedIn
              &gt;<i style="color: #DD4400">...</i>&lt;/#if&gt;</tt> or
              <tt style="color: #A03D10">&lt;#if price ==
              0&gt;<i style="color: #DD4400">...</i>&lt;/#if&gt;</tt>; in
              the last case the result of the <tt style="color: #A03D10">price == 0</tt>
              part is a boolean value.</p>

              <p>In the templates you can directly specify a boolean with
              the reserved words <tt style="color: #A03D10">true</tt> and
              <tt style="color: #A03D10">false</tt>.</p>
            </li>

            <li>
              <p>Date: A date variable stores date/time related
              data. It has three variations:</p>

                  <div class="itemizedlist">
<ul>
                <li>
                  <p>A date with day precision (often referred simply as
                  &quot;date&quot;) as April 4, 2003</p>
                </li>

                <li>
                  <p>Time of day (without the date part), as 10:19:18 PM.
                  Time is stored with millisecond precision.</p>
                </li>

                <li>
                  <p>Date-time (sometimes called &quot;time stamp&quot;) as April 4,
                  2003 10:19:18 PM. The time part is stored with millisecond
                  precision.</p>
                </li>
              </ul>    </div>


              <p>Unfortunately, because of the limitations of the Java
              platform, FreeMarker sometimes can't decide which parts of the
              date are in use (i.e., if it is date-time, or a time of day,
              etc.). The solution for this problem is an advanced topic that
              will be discussed <a href="ref_builtins_date.html#ref_builtin_date_datetype">later</a>.</p>

              <p>It is possible to define date values directly in
              templates, but this is an advanced topic that will be explained
              <a href="ref_builtins_string.html#ref_builtin_string_date">later</a>.</p>
            </li>
          </ul>    </div>


          <p>Bear in mind that FreeMarker distinguishes strings from
          numbers and booleans, so the string <tt style="color: #A03D10">&quot;150&quot;</tt> and the
          number <tt style="color: #A03D10">150</tt> are totally different. A number holds
          a numerical value. A boolean holds a logical true or false. A string
          holds an arbitrary sequence of characters.</p>
        
            
  
  
  
  <h2 class="rank_section2"
        >
<a name="dgui_datamodel_container"></a>Containers  </h2>


          

          <p>These are the values whose purpose is to contain other
          variables; they are just containers. The contained variables are
          often referred as <i>subvariables</i>. The container
          types are:</p>

              <div class="itemizedlist">
<ul>
            <li>
              <p>Hash: Associates a unique lookup name with each of
              its subvariables. The name is an unrestricted string. A hash
              <i>doesn't define an ordering</i> for the
              subvariables in it. That is, there is no such thing as the first
              subvariable, and the second subvariable, etc.; the variables are
              just accessed by name.</p>
            </li>

            <li>
              <p>Sequence: Associates an integer number with each
              of its subvariables. The first subvariable is associated with 0,
              the second with 1, the third to 2, and so on; the subvariables
              are ordered. These numbers are often called the
              <i>indexes</i> of the subvariables. Sequences are
              usually dense, i.e., all indexes up to the index of the last
              subvariable have an associated subvariable, but it's not
              strictly necessary. The type of the subvariable values need not
              be the same.</p>
            </li>

            <li>
              <p>Collection: A collection, from the viewpoint of
              the template author, is a restricted sequence. You cannot access
              its size or retrieve its subvariables by index, but they can be
              still listed with the <a href="ref_directive_list.html#ref.directive.list"><tt>list</tt>
              directive</a>.</p>
            </li>
          </ul>    </div>


          <p>Note that since <a href="dgui_datamodel_basics.html#topic.multitype">a value can
          have multiple types</a>, it is possible for a value to be both a
          hash and a sequence, in which case it would support index-based
          access as well as access by lookup name. However, typically a
          container will be either a hash or a sequence, not both.</p>

          <p>As the value of the variables stored in hashes and sequences
          (and collections) can be anything, it can be a hash or sequence (or
          collection) as well. This way you can build arbitrarily deep
          structures.</p>

          <p>The data-model itself (or better said the root of it) is a
          hash.</p>
        
            
  
  
  
  <h2 class="rank_section2"
        >
<a name="autoid_15"></a>Subroutines  </h2>


          
              
  
  
  
  <h3 class="rank_section3"
        >
<a name="dgui_datamodel_method"></a>Methods and functions  </h3>


            <a name="topic.designer.methodVariable"></a>

            

            <p>A value that is a method or a function is used to calculate
            another value, influenced by the parameters you give to it.</p>

            <p><span style="color:#333399; font-style:italic">For programmer types:
            Methods/functions are first-class values, just like in functional
            programming languages. This means that functions/methods can be
            the parameters or return values of other functions/methods, you
            can assign them to variables, and so on.</span></p>

            <p>Suppose that programmers have put the method variable
            <tt style="color: #A03D10">avg</tt> in the data-model that can be used to
            calculate the average of numbers. If you give the 3 and 5 as
            parameters when you access <tt style="color: #A03D10">avg</tt>, then you get
            the value 4.</p>

            <p>The usage of methods will be explained <a href="dgui_template_exp.html#dgui_template_exp_methodcall">later</a>, but perhaps
            this example helps to understand what methods are:</p>

            <div align="left" class="programlisting"><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
The average of 3 and 5 is: ${avg(3, 5)}
The average of 6 and 10 and 20 is: ${avg(6, 10, 20)}
The average of the price of a python and an elephant is:
${avg(animals.python.price, animals.elephant.price)}&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


            <p>this will output:</p>

            <div align="left" class="programlisting"><table bgcolor="#CCFFCC" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#CCFFCC" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
The average of 3 and 5 is: 4
The average of 6 and 10 and 20 is: 12
The average of the price of a python and an elephant is:
4999.5&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


            <p>What is the difference between a method and a function? As
            far as the template author is concerned, nothing. Well not really
            nothing, as methods typically come from the data-model (<span style="color:#333399; font-style:italic">as they reflect the methods of Java
            objects</span>), and functions are defined in templates (with
            the <a href="ref_directive_function.html#ref.directive.function"><tt>function</tt>
            directive</a> -- an advanced topic), but both can be used on
            the same way.</p>
          

          
              
  
  
  
  <h3 class="rank_section3"
        >
<a name="dgui_datamodel_userdefdir"></a>User-defined directives  </h3>


            

            

            

            <p>A value of this type can be used as user-defined directive
            (with other words, as FreeMarker tag). An user-defined directive
            is a subroutine, something like a little reusable template
            fragment. But this is an advanced topic that will be explained
            <a href="dgui_misc_userdefdir.html">later</a> in its own
            chapter.</p>

            <p><span style="color:#333399; font-style:italic">For programmer types:
            user-defined directives (such as macros), are first-class values
            too, just like functions/methods are.</span></p>

            <p>Just to get an idea about user-defined directives (so just
            ignore this if you won't understand), assume we have a variable,
            <tt style="color: #A03D10">box</tt>, whose value is a user-defined directive
            that prints some kind of fancy HTML message box with a title bar
            and a message in it. The <tt style="color: #A03D10">box</tt> variable could be
            used in the template like this (for example):</p>

            <div align="left" class="programlisting"><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
&lt;@<b>box</b> title=&quot;Attention!&quot;&gt;
  Too much copy-pasting may leads to
  maintenance headaches.
&lt;/@<b>box</b>&gt;&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>

          

          
              
  
  
  
  <h3 class="rank_section3"
        >
<a name="autoid_16"></a>Function/method versus user-defined directive  </h3>


            <p>This is for advanced users again (so ignore it if you don't
            understand). It's a frequent dilemma if you should use a
            function/method or an user-defined directive to implement
            something. The rule of thumb is: Implement the facility as
            user-defined directive instead of as function/method if:</p>

                <div class="itemizedlist">
<ul>
              <li>
                <p>... the output (the return value) is markup (HTML, XML,
                etc.). The main reason is that the result of functions are
                subject to automatic XML-escaping (due to the nature of
                <tt style="color: #A03D10">${<i style="color: #DD4400">...</i>}</tt>), while
                the output of user-defined directives are not (due to the
                nature of
                <tt style="color: #A03D10">&lt;@<i style="color: #DD4400">...</i>&gt;</tt>;
                its output is assumed to be markup, and hence already
                escaped).</p>
              </li>

              <li>
                <p>... it's the side-effect that is important and not the
                return value. For example, a directive whose purpose is to add
                an entry to the server log is like that. (In fact you can't
                have a return value for a user-defined directive, but some
                kind of feedback is still possible by setting non-local
                variables.)</p>
              </li>

              <li>
                <p>... it will do flow control (like for example
                <tt style="color: #A03D10">list</tt> or <tt style="color: #A03D10">if</tt> directives
                do). You just can't do that with a function/method
                anyway.</p>
              </li>
            </ul>    </div>


            <p>The Java methods of FreeMarker-unaware Java objects are
            normally visible as methods in templates, regardless of the nature
            of the Java method. That said, you have no choice there.</p>
          
        
            
  
  
  
  <h2 class="rank_section2"
        >
<a name="autoid_17"></a>Miscellaneous  </h2>


          
              
  
  
  
  <h3 class="rank_section3"
        >
<a name="dgui_datamodel_node"></a>Nodes  </h3>


            

            <p>Node variables represent a node in a tree structure, and are
            used mostly with <a href="xgui.html">XML processing</a>, which
            is an advanced, and specialized topic.</p>

            <p>Still, a quick overview <i>for advanced
            users</i>: A node is similar to a sequence that stores
            other nodes, which are often referred as the children nodes. A
            node stores a reference to its container node, which is often
            referred as the parent node. The main point of being a node is the
            topological information; other data must be stored by utilizing
            that a value can have multiple types. Like, a value may be both a
            node and a number, in which case it can store a number as the
            &quot;pay-load&quot;. Apart from the topological information, a node can
            store some metainformation as well: a node name, a node type
            (string), and a node namespace (string). For example, if the node
            symbolizes a <tt style="color: #A03D10">h1</tt> element in an XHTML document,
            then its name could be <tt style="color: #A03D10">&quot;h1&quot;</tt>, it's node type
            could be <tt style="color: #A03D10">&quot;element&quot;</tt>, and it's namespace could be
            <tt style="color: #A03D10">&quot;http://www.w3.org/1999/xhtml&quot;</tt>. But it's up to
            the designer of the data-model if what meaning these
            metainformations have, and if they are used at all. The way of
            retrieving the topological and metainformations is described <a href="ref_builtins_node.html">in a later chapter</a> (that you
            don't have to understand at this point).</p>
          
          
</div>

    <div class="navigation">
    <div class="pagers">
      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
<div class="pagerButton"><a href="dgui_template.html"><span class="hideA">Next page: </span>The Template</a></div><div class="pagerButton"><a href="dgui_datamodel_basics.html">Previous page</a></div><div class="pagerButton"><a href="dgui_datamodel.html">Parent page</a></div><div class="pagerButton"><a href="index.html">Contents</a></div>      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
    </div>
    <div class="breadcrumb">
<span class="breadcrumb">        You are here:
          <a href="index.html">Book</a>
            <b>></b>
          <a href="dgui.html">Template Author's Guide</a>
            <b>></b>
          <a href="dgui_datamodel.html">Values, Types</a>
            <b>></b>
          The types
</span>    </div>
    </div>

<table border=0 cellspacing=0 cellpadding=0 width="100%">
    <tr>
      <td colspan=2><img src="docgen-resources/img/none.gif" width=1 height=8 alt=""></td>
    <tr>
      <td align="left" valign="top"><span class="smallFooter">
            FreeMarker Manual -- For FreeMarker 2.3.16
            <br>
          HTML generated: 2009-12-08 08:38:54 GMT
      </span></td>
      <td align="right" valign="top"><span class="smallFooter">
          <a href="http://www.xmlmind.com/xmleditor/">
            <img src="docgen-resources/img/xxe.gif" alt="Edited with XMLMind XML Editor">
          </a>
      </span></td>
    </tr>
</table>
  <!-- Put pre-loaded images here: -->
  <div style="display: none">
    <img src="docgen-resources/img/linktargetmarker.gif" alt="Here!" />
  </div>
</body>
</html>

